// Copyright (c) Appeon. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

namespace SnapObjects.Data
{
    /// <summary>
    ///     Represents an object that is used to add sorting criteria to the ORDER BY clause of the SQL statement.
    ///     The ORDER BY clause sorts the data returned by the query.
    /// </summary>
    public interface ISqlOrderThenBuilder : ISqlBuilder
    {
        /// <summary>
        ///     Adds one or more sort criteria (in ascending order) to the ORDER BY clause.
        /// </summary>
        /// <param name="orderExpressions">
        ///     (Optional) An array of expressions which specify a column or an expression on which to sort the query result set.
        /// </param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BYclause.
        /// </returns>
        ISqlOrderThenBuilder ThenByAscending(params string[] orderExpressions);

        /// <summary>
        ///     Adds one or more sort criteria (in descending order) to the ORDER BY clause.
        /// </summary>
        /// <param name="orderExpressions">
        ///     (Optional) An array of expressions which specify a column or an expression on which to sort the query result set.
        /// </param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BYclause.
        /// </returns>
        ISqlOrderThenBuilder ThenByDescending(params string[] orderExpressions);

        /// <summary>
        ///     Adds one or more sort criteria specified by raw SQL to the ORDER BY clause.
        /// </summary>
        /// <param name="orderClause">
        ///     A string of raw SQL which specifies one or more sort criteria.
        /// </param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BY clause.
        /// </returns>
        ISqlOrderThenBuilder ThenByRaw(string orderClause);

        /// <summary>
        ///     Adds one or more sort criteria specified by raw SQL to the ORDER BY clause, and specifies an alias for the raw SQL.
        /// </summary>
        /// <param name="orderClause">
        ///     A string of raw SQL which specifies one or more sort criteria.
        /// </param>
        /// <param name="alias">
        ///     The alias for the raw SQL.
        /// </param>
        /// <returns>
        ///     Returns an ISqlOrderThenBuilder object which can be used to add more sort criteria to the current ORDER BY clause.
        /// </returns>
        ISqlOrderThenBuilder ThenByRaw(string orderClause, string alias);
    }
}
